<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<TITLE>Using Apache with Microsoft Windows</TITLE>
</HEAD>

<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
<BODY
 BGCOLOR="#FFFFFF"
 TEXT="#000000"
 LINK="#0000FF"
 VLINK="#000080"
 ALINK="#FF0000"
>
<!--#include virtual="header.html" -->

<H1 ALIGN="CENTER"><A NAME="help">Using Apache With Microsoft Windows</A></H1>

<P>This document explains how to install, configure and run Apache 1.3 under 
   Microsoft Windows. Please note that at this time, Windows support is 
   entirely experimental, and is recommended only for experienced users. 
   The Apache Group does not guarantee that this software will work as 
   documented, or even at all. If you find any bugs, please document them on
   our <A HREF="http://www.apache.org/bug_report.html">bug reporting page.</A>
   Contributions are welcomed, please submit your code or suggestions to the 
   bug report page, or join the new-httpd mailing list.</P>

<P>The bug reporting page and new-httpd mailing list are <EMP>not</EMP> 
   provided to answer questions about configuration or running Apache.  
   Before you submit a bug report or request, first consult this document, the 
   <A HREF="misc/FAQ.html">Frequently Asked Questions</A> page and the other 
   relevant documentation topics.  If you still have a question or problem, 
   post it to the <A HREF="news:comp.infosystems.www.servers.ms-windows">
   comp.infosystems.www.servers.ms&minus;windows</A> newsgroup, where many 
   Apache users and several contributions are more than willing to answer new 
   and obscure questions about using Apache on Windows.</P>

<P><A HREF="http://www.deja.com/group/comp.infosystems.www.servers.ms-windows">
   deja.com's newsgroup archives</A> offer easy browsing of previous questions.
   Searching the newsgroup archives, you will usually find your question was 
   already asked and answered by other users!</P>

<P><STRONG>Warning: Apache on NT has not yet been optimized for performance.
   </STRONG>Apache still performs best, and is most reliable on Unix platforms.
   Over time we will improve NT performance, and great progress is being made
   in the upcoming version 2.0 of Apache for the Windows platforms. Folks doing
   comparative reviews of webserver performance are asked to compare against 
   Apache on a Unix platform such as Solaris, FreeBSD, or Linux.</P>

<P>Most of this document assumes that you are installing Windows from a
   binary distribution. If you want to compile Apache yourself (possibly
   to help with development, or to track down bugs), see 
   <A HREF="win_compiling.html">Compiling Apache for Microsoft Windows</A>.

<HR>

<UL>
  <LI><A HREF="#req">Requirements</A>
  <LI><A HREF="#down">Downloading Apache for Windows</A>
  <LI><A HREF="#inst">Installing Apache for Windows (binary install)</A>
  <LI><A HREF="#run">Running Apache for Windows</A>
  <LI><A HREF="#test">Testing Apache for Windows</A>
  <LI><A HREF="#use">Configuring Apache for Windows</A>
  <LI><A HREF="#cmdline">Running Apache in a Console Window</A>
  <LI><A HREF="#signal">Controlling Apache in a Console Window</A>
  <LI><A HREF="win_service.html">Running Apache for Windows as a Service</A>
  <LI><A HREF="win_service.html#signal">Controlling Apache as a Service</A>
  <LI><A HREF="win_compiling.html">Compiling Apache for Microsoft Windows</A>
</UL>

<HR>

<H2><A NAME="req">Requirements</A></H2>

<P>Apache 1.3 is designed to run on Windows NT 4.0 and Windows 2000.
   The binary installer will only work with the x86 family of processors, 
   such as Intel's. Apache may also run on Windows 95 and 98, but these have 
   not been tested. In all cases TCP/IP networking must be installed.</P>

<P>If running on NT 4.0, installing Service Pack 3 or 6 is recommended, as
   Service Pack 4 created known issues with TCPIP/WinSock integrity that
   were resolved in later Service Packs.</P>

<P><STRONG>Note: "Winsock 2" is required for Apache 1.3.7 and 
   later.</STRONG></P>

<P>If running on Windows 95, the "Winsock2" upgrade must be installed
   before Apache will run. "Winsock2" for Windows 95 is available
   <A HREF="http://www.microsoft.com/windows95/downloads/contents/WUAdminTools/S_WUNetworkingTools/W95Sockets2/Default.asp">here</a>
   or via <A HREF="http://www.microsoft.com/windows95/downloads/">here</A>.
   Be warned that the Dialup Networking 1.2 (MS DUN) updates include a Winsock2
   that is entirely insufficient, and the Winsock2 update must be reinstalled
   after installing Windows 95 dialup networking.</P>


<H2><A NAME="down">Downloading Apache for Windows</A></H2>

<P>Information on the latest version of Apache can be found on the
   Apache web server at <A HREF="http://www.apache.org/httpd">
   http://www.apache.org/httpd</A>.  This will
   list the current release, any more recent alpha or beta-test releases,
   together with details of mirror web and anonymous FTP sites.</P>

<P>You should download the version of Apache for Windows with the
   <CODE>.exe</CODE> extension. This is a single file containing Apache,
   ready to install and run. There may also be a <CODE>.zip</CODE> file
   containing the source code, to compile Apache yourself.  (If there is
   no <SAMP>.zip</SAMP> file, the source will be available in a
   <SAMP>.tar.gz</SAMP> file but this will contain Unix line endings. You
   will have to convert at least the <SAMP>.mak</SAMP> and
   <SAMP>.dsp</SAMP> files to have DOS line endings before MSVC will
   understand them).</P>

<H2><A NAME="inst">Installing Apache for Windows</A></H2>

<P>Run the Apache <SAMP>.exe</SAMP> file you downloaded above. This will
   ask for:</P>

<UL>

 <LI>the directory to install Apache into (the default is 
    <CODE>\Program Files\Apache Group\Apache</CODE> although you can
    change this to any other directory)

 <LI>the start menu name (default is "Apache Web Server")

 <LI>the installation type. The "Typical" option installs
    everything except the source code. The "Minimum" option does not
    install the manuals or source code. Choose the "Custom" install if
    you want to install the source code.

</UL>

<P>During the installation, Apache will configure the files in the
   <SAMP>conf</SAMP> directory for your chosen installation
   directory. However if any of the files in this directory already exist
   they will <STRONG>not</STRONG> be overwritten. Instead the new copy of
   the corresponding file will be left with the extension
   <SAMP>.default</SAMP>. So, for example, if
   <SAMP>conf\httpd.conf</SAMP> already exists it will not be altered,
   but the version which would have been installed will be left in
   <SAMP>conf\httpd.conf.default</SAMP>. After the installation has
   finished you should manually check to see what in new in the
   <SAMP>.default</SAMP> file, and if necessary update your existing
   configuration files.</P>

<P>Also, if you already have a file called <SAMP>htdocs\index.html</SAMP>
   then it will not be overwritten (no <SAMP>index.html.default</SAMP>
   file will be installed either). This should mean it is safe to install
   Apache over an existing installation (but you will have to stop the
   existing server running before doing the installation, then start the
   new one after the installation is finished).</P>

<P>After installing Apache, you should edit the configuration files in
   the <SAMP>conf</SAMP> directory as required. These files will be
   configured during the install ready for Apache to be run from the
   directory where it was installed, with the documents served from the
   subdirectory <SAMP>htdocs</SAMP>. There are lots of other options
   which should be set before you start really using Apache. However to
   get started quickly the files should work as installed.</P>

<H2><A NAME="run">Running Apache for Windows</A></H2>

<P>There are two ways you can run Apache:</P>

<UL>
 <LI>As a <A HREF="win_service.html">"service"</A> (tested on NT/2000 only, 
   but an <EM>experimental</EM> version is available for 95/98).
   This is the best option if you want Apache to automatically start when your
   machine boots, and to keep Apache running when you log-off.
 <LI>From a <A HREF="#cmdline">console window</A>. This is the best option
   available for Windows 95/98 users.
</UL>

<P><STRONG>Complete the steps below before you attempt to start Apache 
   as a Windows "<A HREF="win_service.html">service</A>"!</STRONG></P>

<P>To run Apache from a console window, select the "Start Apache as
   console app" option from the Start menu (in Apache 1.3.4 and earlier,
   this option was called "Apache Server"). This will open a console
   window and start Apache running inside it. The window will remain
   active until you stop Apache. To stop Apache running, either press select
   the "Shutdown Apache console app" icon option from the Start menu
   (this is not available in Apache 1.3.4 or earlier), or see
   <A HREF="#signal">Controlling Apache in a Console Window</A> for commands
   to control Apache in a console window.</P>

<P>In Apache 1.3.13 and above it is now quite safe to press Ctrl+C or 
   Ctrl+Break to stop the Apache in the console window.  And on Windows NT/2000
   with version 1.3.13, Apache will also gladly stop if you select 'Close'
   from the system menu (clicking the icon on the top-left corner of the
   console window) or click the close (X) button on the top-right corner.
   But do <EM>not</em> try any of these approaches on earlier versions of the
   Apache server, since Apache did not shut down cleanly.</P>

<H2><A NAME="test">Testing Apache for Windows</A></H2>

<P>If you have trouble starting Apache please use the following steps to 
   isolate the problem. This applies if you started Apache using the
   "Start Apache as a console app" shortcut from the Start menu and
   the Apache console window closes immediately (or unexpectedly)
   or if you have trouble starting Apache as a service.</P>
	 
<P>Run the "Command Prompt" from the Start Menu - Programs list.  Change
   to the folder to which you installed Apache, type the command apache, and 
   read the error message.  Then review the error.log file for configuration 
   mistakes.  If you accepted the defaults when you installed Apache, the 
   commands would be:</P>

<PRE>
  c:
  cd "\program files\apache group\apache"
  apache
  <EM>Wait for Apache to exit, or press </EM>Ctrl+C
  more &lt;logs\error.log
</PRE>

<P>After looking at the error.log you will probably have a good chance of 
   working out what went wrong and be able to fix the problem and try again. 
   If you are unable to work it out then please follow the 
   <A HREF="#help">guidelines for assistance</A> at the top of this document 
   or in the <a href="misc/FAQ.html#what2do">FAQ</a>. Many users discover that
   the nature of the httpd.conf file is easier to manage and audit than page 
   after page of configuration dialog boxes.</P>

<P>After starting Apache running (either in a console window or as a
   service) if will be listening to port 80 (unless you changed the
   <SAMP>Port</SAMP>, <SAMP>Listen</SAMP> or <SAMP>BindAddress</SAMP>
   directives in the configuration files). To connect to the server and
   access the default page, launch a browser and enter this URL:</P>

<PRE>
  http://localhost/
</PRE>

<P>This should respond with a welcome page, and a link to the Apache
   manual. If nothing happens or you get an error, look in the
   <SAMP>error.log</SAMP> file in the <SAMP>logs</SAMP> directory.
   If your host isn't connected to the net, you may have to use
   this URL:</P>

<PRE>
  http://127.0.0.1/
</PRE>

<P>Once your basic installation is working, you should configure it
   properly by editing the files in the <SAMP>conf</SAMP> directory.</P>

<P>Because Apache <EM>CANNOT</EM> share the same port with another
   TCP/IP application, you may need to stop or uninstall certain 
   services first.  These include (but are not limited to) other
   web servers, and firewall products such as BlackIce.  If you can
   only start Apache with these services disabled, reconfigure either
   Apache or the other product so that they do not listen on the
   same TCP/IP ports. You may find the Windows "netstat -an" command useful
   in finding out what ports are in use.</P>

<H2><A NAME="use">Configuring Apache for Windows</A></H2>

<P>Apache is configured by files in the <SAMP>conf</SAMP>
   directory. These are the same as files used to configure the Unix
   version, but there are a few different directives for Apache on
   Windows. See the <A HREF="./">Apache documentation</A> for all the
   available directives.</P>

<P>Begin configuring the Apache server by reviewing <CODE>httpd.conf</CODE> 
   and it's directives.  Although the files <CODE>access.conf</CODE> and
   <CODE>srm.conf</CODE> both exist, these are old files which are no longer
   used by most administrators, and you will find no directives there.</P>

<P><CODE>httpd.conf</CODE> contains a great deal of documentation itself,
   followed by the default configuration directives recommended when starting
   with the Apache server.  Begin by reading these comments to understand the 
   configuration file, and make small changes, starting Apache in a console 
   window with each change.  If you make a mistake, it will be easier to back 
   up to configuration that last worked.  You will have a better idea of
   which change caused the server to fail.</P>

<P>The main differences in Apache for Windows are:</P>

<UL>
  <LI>Because Apache for Windows is multithreaded, it does not use a
      separate process for each request, as Apache does with
      Unix. Instead there are usually only two Apache processes running:
      a parent process, and a child which handles the requests. Within
      the child each request is handled by a separate thread.  So, 
      "process"-management directives are different:
    <UL>
      <LI><A HREF="mod/core.html#maxrequestsperchild">MaxRequestsPerChild</A>
         - Like the Unix directive, this controls how many requests a
           process will serve before exiting. However, unlike Unix, a
           process serves all the requests at once, not just one, so if
           this is set, it is recommended that a very high number is
           used. The recommended default, <CODE>MaxRequestsPerChild
           0</CODE>, does not cause the process to ever exit.
      <LI><A HREF="mod/core.html#threadsperchild">ThreadsPerChild</A> -
         This directive is new, and tells the server how many threads it
         should use. This is the maximum number of connections the server
         can handle at once; be sure and set this number high enough for
         your site if you get a lot of hits. The recommended default is
         <CODE>ThreadsPerChild 50</CODE>.
    </UL>
  <LI>The directives that accept filenames as arguments now must use
      Windows filenames instead of Unix ones. However, because Apache
      uses Unix-style names internally, you must use forward slashes, not
      backslashes. Drive letters can be used; if omitted, the drive with
      the Apache executable will be assumed.
  <LI>Apache for Windows has the ability to load modules at runtime,
      without recompiling the server. If Apache is compiled normally, it
      will install a number of optional modules in the
      <CODE>\modules</CODE> directory. To activate these, or other
      modules, the new <A HREF="mod/mod_so.html#loadmodule">LoadModule</A>
      directive must be used. For example, to active the status module,
      use the following (in addition to the status-activating directives
      in <CODE>access.conf</CODE>):
  <LI>Apache for Windows version 1.3 series is implemented in synchronous
      calls.  This poses an enormous problem for CGI authors, who won't
      see unbuffered results sent immediately to the browser.  This is not
      the behavior described for CGI in Apache, but it is a side-effect of
      the Windows port.  Apache 2.0 is making progress to implement the
      expected asynchronous behavior, and we hope to discover that the
      NT/2000 implementation allows CGI's to behave as documented.
<PRE>
    LoadModule status_module modules/ApacheModuleStatus.dll
</PRE>
      <P>Information on <A HREF="mod/mod_so.html#creating">creating loadable
         modules</A> is also available.</P>
  <LI><P>Apache can also load ISAPI Extensions (<EM>i.e.</EM>, Internet Server
         Applications), such as those used by Microsoft's IIS, and other
         Windows servers. <A HREF="mod/mod_isapi.html">More information
         is available.</A>  Note that Apache <EM>CANNOT</EM> load ISAPI
		 Filters.
</UL>


<H2><A NAME="cmdline">Running Apache in a Console Window</A></H2>

<P>The Start menu icons and the NT Service manager can provide a simple
   interface for administering Apache. But in some cases it is easier to
   work from the command line.</P>

<P>When working with Apache it is important to know how it will find the
   configuration files.  You can specify a configuration file on the command 
   line in two ways:</P>

<UL>
<LI>-f specifies a path to a particular configuration file:
</UL>
<PRE>    apache -f "c:\my server\conf\my.conf"</PRE>
<PRE>    apache -f test\test.conf</PRE>
<UL>
<LI>-n specifies the configuration file of an installed Apache service (Apache 1.3.7 and later):
</UL>
<PRE>    apache -n "service name"</PRE>

<P>In these cases, the proper ServerRoot should be set in the configuration 
   file.</P>

<P>If you don't specify a configuration file name with -f or -n, Apache will
   use the file name compiled into the server, usually "conf/httpd.conf".  
   Invoking Apache with the -V switch will display this value labeled as 
   SERVER_CONFIG_FILE. Apache will then determine its ServerRoot by trying 
   the following, in this order:</P>

<UL>
<LI>A ServerRoot directive via a -C switch.
<LI>The -d switch on the command line.
<LI>The current working directory
<LI>A registry entry, created if you did a binary install.
<LI>The server root compiled into the server.
</UL>

<P>The server root compiled into the server is usually "/apache".
   invoking apache with the -V switch will display this value
   labeled as HTTPD_ROOT.</P>

<P>When invoked from the start menu, Apache is usually passed no arguments,
   so using the registry entry is the preferred technique for console Apache.
   </P>

<P>During a binary installation, a registry key will have
   been installed, for example:</P>

<PRE>
  HKEY_LOCAL_MACHINE\Software\Apache Group\Apache\1.3.13\ServerRoot
</PRE>

<P>This key is compiled into the server and can enable you to test 
   new versions without affecting the current version.  Of course
   you must take care not to install the new version on top of the
   old version in the file system.</P>

<P>If you did not do a binary install then Apache will in some
   scenarios complain about the missing registry key.  This
   warning can be ignored if it otherwise was able to find its
   configuration files.

<P>The value of this key is the "ServerRoot" directory, containing the
   <SAMP>conf</SAMP> directory. When Apache starts it will read the
   <SAMP>httpd.conf</SAMP> file from this directory. If this file
   contains a <SAMP>ServerRoot</SAMP> directive which is different from
   the directory obtained from the registry key above, Apache will forget
   the registry key and use the directory from the configuration file.
   If you copy the Apache directory or configuration files to a new
   location it is vital that you update the <SAMP>ServerRoot</SAMP>
   directory in the <SAMP>httpd.conf</SAMP> file to the new location.</P>

<P>To run Apache from the command line as a console application, use the
   following command:</P>

<PRE>
    apache 
</PRE>

<P>Apache will execute, and will remain running until it is stopped by pressing
   control-C.</P>

<H2><A NAME="signal">Controlling Apache in a Console Window</A></H2>

<P>You can tell a running Apache to stop by opening another console window and 
   running:</P>

<PRE>
    apache -k shutdown
</PRE>

<P><STRONG>Note: This option is only available with Apache 1.3.3 and
   later.</STRONG></P>

<P>For earlier versions, you must use Control-C in the
   Apache console window to shut down the server.</P>

<P>From version 1.3.3 through 1.3.12, this should be used instead of pressing
   Control-C in a running Apache console window, because it allowed Apache 
   to end any current transactions and cleanup gracefully.</P>

<P>As of version 1.3.13 pressing Control-C in the running window will cleanup 
   Apache quite gracefully, and you may use -k stop as an alias for 
   -k shutdown.  Earlier versions do not understand -k stop.</P>

<P>You can also tell Apache to restart. This makes it re-read the
   configuration files. Any transactions in progress are allowed to
   complete without interruption. To restart Apache, run:</P>

<PRE>
    apache -k restart
</PRE>

<P><STRONG>Note: This option is only available with Apache 1.3.3 and
   later.  For earlier versions, you need to use Control-C in the
   Apache console window to shut down the server, and then restart the
   server with the Apache command.</STRONG></P>

<P>Another <EM>very useful</EM> feature is the configuration files test option.
   To test the Apache configuration files, run:</P>

<PRE>
    apache -t
</PRE>

<P>This is especially useful following alterations to the configuration files
   while Apache is still running. You can make the changes, confirm that the 
   syntax is good by issuing the "apache -t" command, then restart Apache with
   "apache -k restart". Apache will re-read the configuration files, allowing 
   any transactions in progress to complete without interruption. Any new 
   request will then be served using the new configuration.</P>

<P>Note: for people familiar with the Unix version of Apache, these commands 
   provide a Windows equivalent to <CODE>kill -TERM <EM>pid</EM></CODE> and 
   <CODE>kill -USR1 <EM>pid</EM></CODE>. The command line option used, 
   <CODE>-k</CODE>, was chosen as a reminder of the "kill" command used on 
   Unix.</P>

<!--#include virtual="footer.html" -->
</BODY>
</HTML>

